Copyright: TMailslot Components v1.0


Help Contents

This Help describes the functionality of the components TMailslotServer, TMailslotClient and TMailslotTerminal.

What is a mailslot

How to install TMailslot components

TMailslotServer component

TMailslotClient component

TMailslotTerminal component

Properties

Methods

Events

Exceptions

Feedback

How to register and/or obtain the source code

Copyright


What is a mailslot

A mailslot is a mechanism for one-way interprocess communications (IPC). An application written for Microsoft® Windows® can store messages in a mailslot. The owner of the mailslot can retrieve messages that are stored there. These messages are typically sent over a network to either a specified computer or to all computers in a specified domain. A domain is a group of workstations and servers that share a group name.

A mailslot is a pseudofile; it resides in memory, and standard Windows file functions write to it. Unlike disk files, however, mailslots are temporary. When every handle of a mailslot is closed, the mailslot and all the data it contains are deleted. The data in a mailslot can be in any form.

Mailslots can broadcast messages within a domain. If several processes in a domain each create a mailslot using the same name, every message that is addresses to that mailslot and sent to the domain is received by the participating processes.

Datagrams are used by mailslots. A datagram is a small packet of information that the network sends along the wire. Like a radio or television broadcast, a datagram offers no confirmation of receipt; there is no way to guarantee that a datagram has been received. Just as mountains, large buildings, or interfering signals might cause a radio or television signal to get lost, there are things the sender has no knowledge of that can prevent a datagram from reaching a particular destination.


How to install TMailslot components

To Install the Components

Delphi 2.0 (32 Bit)

1. Choose the Install option from the component menu.

2. Press the Add Button

3. Select MAILSLOT.DCU changing the path if necessary.

4. Press OK Twice.

5. The components are now installed onto the system tab of the component selector.

To Install the Components Help

(These instructions assume that your copy of Delphi is installed in C:\DELPHI

 If not adjust the paths accordingly)

1. Copy MAILSLOT.KWF to C:\DELPHI\HELP.

2. Copy MAILSLOT.HLP to C:\DELPHI\BIN.

3. Run HELPINST from your delphi folder.

4. Use.FILE|OPEN to open C:\DELPHI\BIN\DELPHI.HDX.

5. Use KEYWORDS|ADD KEYWORD FILE to add C:\DELPHI\HELP\MAILSLOT.KWF.

6. Use FILE|SAVE to Compile and save the new HDX file.

7. Online help is now installed.


TMailslotServer component

The TMailslotServer is a descendent of TComponent. Use a TMailslotServer component to receive messages from processes running on other computers, or even from your own.

A mailslot is identified by MailslotName. You can’t have more than one mailslot in a computer with the same name, but you can have one mailslot with the same name in several computers of the network.

You can retrieve messages from the mailslot with the function ReadMessage. New messages follow preexisting messages.

Attention: You can receive duplicated messages because, for example, if you have three network transports loaded there is no way to know which transport should be used to deliver to a given mailslot on a remote machine, so all transports are used.

Properties:

Handle

InheritHandle

Interval

MailslotName

MaxMessageSize

MessagePolling

MessageSize

NumberMessages

ReadTimeOut

ThreadPriority

Methods:

GetCreationTime

SetCreationTime

ReadMessage

Events:

OnNewMessage

Exceptions:

EMailslotServerError


TMailslotClient component

The TMailslotClient is a descendent of TComponent. You use a TMailslotClient component to send messages to processes running on other computers, or to your own. The messages can be received by a TMailslotServer component.

You identify your receiver by declaring his MailslotName, Receiver and ReceiverName. If you want to send a messages to a single computer you need to know his MailslotName, set Receiver to  rcDomainOrComputer and fill ReceiverName with the computer’s name.

Otherwise, if you want to send messages within the system’s primary domain, just initialize the MailslotName and set Receiver to rcPrimaryDomain. In this case every mailslot with the given name in the primary domain will receive it.

After identifying your receiver(s), to send a message you just need to call WriteMessage.

Properties:

Handle

MailslotName

Receiver

ReceiverName

Methods:

WriteMessage

Exceptions:

EMailslotClientError


TMailslotTerminal component

The TMailslotTerminal is a descendent of TComponent. With this component you may send and receive messages across a Windows Network.

TMailslotTerminal is a conjunction of both TMailslotServer and TMailslotClient components, usually you’ll just use this one.

The MailslotName property identifies your mailslot for sending messages as well as receiving. Additionally, there’s a UniqueID property you can use to identify your computer in the network.

Whenever you receive a new message the OnNewMessage event occurs and makes it available through the Message property.

Attention: The problem of receiving duplicated messages isn’t present in this component, as with TMailslotServer, because there’s made a validation on received messages, and it’s only delivered the new non-duplicated messages.

To interact with a TMailslotTerminal use only another TMailslotTerminal, don’t use TMailslotClient or TMailslotServer, because it sends some data control together with the original message.

Properties:

Interval

MailslotName

Message

Receiver

ReceiverName

UniqueID

Methods:

WriteMessage

Events:

OnNewMessage


Properties

TMailslotServer, TMailslotClient, TMailslotTerminal properties:

Handle

InheritHandle

Interval

MailslotName

MaxMessageSize

Message

MessagePolling

MessageSize

NumberMessages

ReadTimeOut

Receiver

ReceiverName

ThreadPriority

UniqueID


Methods

TMailslotServer, TMailslotClient, TMailslotTerminal methods:

GetCreationTime

SetCreationTime

ReadMessage

WriteMessage


Events

TMailslotServer event:

OnNewMessageTMailslotTerminal event:

OnNewMessage


Exceptions

TMailslotServer and TMailslotClient exceptions:

EMailslotServerError

EMailslotClientError


Feedback

I would appreciate some feedback, especially bugs or improvements that you think that I should make. In the event of you finding a bug, see if you can reproduce it in a simple piece of code and email me that code. As soon as the bug is fixed you will be sent an intermediate version with the bug fix.

Email: cbarbosa@mail.telepac.pt

URL: http://wwwAlu.ci.uminho.pt:8888/~si14525

Mail:	Carlos Barbosa

Passos - Fajoes

3700 S. J. Madeira

Portugal


How to register and/or obtain the Source Code

The TMailslot components whereby contained are for evaluation purposes only. When used within Borland Delphi, in the application development process, they are fully activated (with no restrictions). However, when running within a self-running .EXE or .DLL file they are completely disabled.

When registered this components have no restrictions and you’ll receive bug fix releases.

The registered version is available directly from the author at a cost of US $15.00 without source code, or US $35.00 with source code. The payment can be made in any other currency by the equivalent amount. Due to the price the source can only be distributed via e-mail.

The payment is made by cash(preferably) or check in order to: Carlos Manuel Amorim Barbosa

and sent by mail to the address specified below.

The author can be contacted at

Email: cbarbosa@mail.telepac.pt

URL: http://wwwAlu.ci.uminho.pt:8888/~si14525

Mail:	Carlos Barbosa

Passos - Fajoes

3700 S. J. Madeira

Portugal


Copyright

There are no restrictions placed on the use of the registered versions of TMailslot components in compiled DCU format or linked into an EXE or DLL..

THE INFORMATION AND CODE PROVIDED HEREUNDER (COLLECTIVELY REFERRED TO AS "SOFTWARE") IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL CARLOS BARBOSA (REFERRED TO AS "AUTHOR") BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

This Software may be used royalty-free subject to the following conditions:

1. You must copy all Software without modification and must include all pages, if the Software is distributed without inclusion in your software product. If you are incorporating the Software in conjunction with and as a part of your software product which adds substantial value, you may modify and include portions of the Software.

2. Unless the Software is incorporated in your software product which adds substantial value, you may not distribute this Software for profit.

3. You agree to indemnify, hold harmless, and defend the Author from and against any claims or lawsuits, including attorneys' fees, that arise or result from the use or distribution of your software product and any modifications to the Software.


Handle property
Handle

Applies to

TMailslotServer, TMailslotClient

Declaration

property Handle: THandle;

Description

Read and run-time only. The Handle gives you access to the mailslot handle or file handle if it’s, respectively, a TMailslotServer or TMailslotClient. If the value is 0 the mailslot or file it’s not created.


InheritHandle property
InheritHandle

Applies to

TMailslotServer

Declaration

property InheritHandle: Boolean;

Description

If you want child processes to be able to inherit the mailslot handle then you have to set this property to True, otherwise you leave it False.


Interval property
Interval

Applies to

TMailslotServer, TMailslotTerminal

Declaration

property Interval: DWord;

Description

Defines the time interval, in milliseconds, between each checking to the mailslot to see if there’s any new message.


MailslotName property
MailslotName

Applies to

TMailslotServer, TMailslotClient, TMailslotTerminal

Declaration

property MailslotName: string;

Description

Defines the mailslot name, which can be preceded by a path consisting of the names of one or more pseudodirectories, separated by backslashes. The mailslot name identifies the pseudofile to which you send or receive messages.

Example

If a user expects messages on the subject of taxes from Bob, Pete and Sue, the user’s mailslot application might allow the user to create individual mailslots for each sender.

MailslotServer1.MailslotName := ‘taxes\bobs_comments’;

MailslotServer2.MailslotName := ‘taxes\petes_comments’;

MailslotServer3.MailslotName := ‘taxes\sues_comments’;


MaxMessageSize property
MaxMessageSize

Applies to

TMailslotServer

Declaration

property MaxMessageSize: DWord;

Description

Specifies the maximum size, in bytes, of a single message that can be written to the mailslots. To specify that the message can be of any size, set this value to zero.


Message property
Message

Applies to

TMailslotTerminal

Declaration

property Message: TMemoryStream;

Description

Read and run-time only. You should use this property to pick up the last message data. This should be done inside the OnNewMessage event procedure.

The first bytes of the stream are occupied with data to prevent duplicated messages, so don’t reset the stream position to 0, read it from the given position.


MessagePolling property
MessagePolling

Applies to

TMailslotServer

Declaration

property MessagePolling: Boolean;

Description

Set this property to True if you want OnNewMessage event to occur when there’s a new message. Otherwise, there will be no polling to check new messages, and the Interval and ThreadPriority values are unused.


MessageSize property
MessageSize

Applies to

TMailslotServer

Declaration

property MessageSize: DWord;

Description

Read and run-time only. Returns the size of the next message in bytes or 0 if none available.


NumberMessages property
NumberMessages

Applies to

TMailslotServer

Declaration

property NumberMessages: DWord;

Description

Read and run-time only. Returns the number of messages on the mailslot.


ReadTimeOut property
ReadTimeOut

Applies to

TMailslotServer

Declaration

property ReadTimeOut: DWord;

Description

Specifies the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. The following values have special meanings:

0	Returns immediately if no message is present. (The system does not treat an immediate return as an error.)

-1	Waits forever for a message.


Receiver property
Receiver

Applies to

TMailslotClient, TMailslotTerminal

Declaration

property Receiver: TReceiverType;

TReceiverType = ( rcLocalComputer, rcPrimaryDomain, rcDomainOrComputer );

Description

Receiver identifies to which mailslots should the connection be made. It can have any of the following values:

              Value                                            Meaning

rcLocalComputer	Connects to a mailslot in the local computer

rcPrimaryDomain	Connects into every mailslot in the system’s primary domain

rcDomainOrComputer	Connects into every mailslot in the specified domain or to a specific remote computer


ReceiverName property
ReceiverName

Applies to

TMailslotClient, TMailslotTerminal

Declaration

property ReceiverName: string;

Description

If the property is set to rcDomainOrComputer the ReceiverName defines the name of a Domain or Computer otherwise this value is ignored.


ThreadPriority property
ThreadPriority

Applies to

TMailslotServer

Declaration

property TThreadPriority: TThreadPriority;

Description

Use this property to set the priority of the thread that takes care of checking the mailslot for new messages. It can take any of the following values:

tpIdle	The thread executes only when the system is idle-Windows won't interrupt other threads to execute a thread with tpIdle priority.

tpLowest	The thread's priority is two points below normal.

tpLower	The thread's priority is one point below normal.

tpNormal	The thread has normal priority.

tpHigher	The thread's priority is one point above normal.

tpHighest	The thread's priority is two points above normal.

tpTimeCritical	The thread gets highest priority.


UniqueID property
UniqueID

Applies to

TMailslotTerminal

Declaration

property UniqueID: DWord;

Description

Read and run-time only. Use this value if you want to identify your computer uniquely. This value is generated when the component is created, combining the current Process ID, User Name and Computer Name values to calculate an unique value.


GetCreationTime method
GetCreationTime

Applies to

TMailslotServer

Declaration

procedure GetCreationTime( var CreationTime: TFILETIME );

Description

Returns the date and time the mailslot was created.


ReadMessage method
ReadMessage

Applies to

TMailslotServer

Declaration

function ReadMessage( var Buffer; Count: DWord ): DWord;

Description

Retrieves a message from the mailslot to Buffer with Count bytes. The function will return when there’s a message available on the mailslot or when it reaches ReadTimeOut milliseconds causing an EMailslotClientError exception. Note that you have to read all message data at once, with one single call.

Returns number of bytes read-


SetCreationTime method
SetCreationTime

Applies to

TMailslotServer

Declaration

procedure SetCreationTime( var CreationTime: TFILETIME );

Description

Sets the date and time the mailslot was created.


WriteMessage method
WriteMessage

Applies to

TMailslotClient, TMailslotTerminal

Declaration

function WriteMessage( var Buffer; Count: DWord ): DWord;

Description

Writes a message to the mailslot from Buffer with Count bytes. There is a limit of 400 bytes to broadcast a message to a domain and 64 kilobytes when isn’t a broadcast.

Returns number of bytes written.


OnNewMessage event
OnNewMessage

Applies to

TMailslotServer

Declaration

property OnNewMessage: TNotifyEvent;

Description

The OnNewMessage event occurs when there’s one or more new messages in the mailslot. This event can be deactivated setting to False the property MessagePolling.


OnNewMessage event
OnNewMessage

Applies to

TMailslotTerminal

Declaration

property OnNewMessage: TNewMessageEvent;

TNewMessageEvent = procedure( Sender: TObject; SenderID: DWord; MsgSize: Word ) of Object;

Description

This event occurs every time a new message arrives into the mailslot. The mailslot is checked every Interval milliseconds. Get the message data reading MsgSize bytes from Message. The SenderID is the UniqueID value of the MailslotTerminal that sent the message.

Example

Here’s how to read a string from the mailslot and show it in a Message Dialog box:

procedure NewMessage(Sender: TObject; SenderID: DWord; MsgSize: Word);

var

   st: string;

begin

   SetLength( st, MsgSize );

   Mt.Message.Read( PChar(st)^, MsgSize );

   MessageDlg( st, mtInformation, [mbOk], 0);

end;


EMailslotServerError exception
EMailslotServerError

Applies to

TMailslotServer

Declaration

EMailslotServer = class(Exception);

Description

This exception is raised if it fails to create a mailslot or reading a message from it. With the function GetLastError you can get the error code.


EMailslotClientError exception
EMailslotClientError

Applies to

TMailslotClient

Declaration

EMailslotClient = class(Exception);

Description

This exception is raised if it fails to create a mailslot connection or writing a message. With the function GetLastError you can get the error code.